home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_perl.idb / usr / freeware / lib / perl5 / 5.00502 / ExtUtils / MakeMaker.pm.z / MakeMaker.pm
Encoding:
Text File  |  1998-10-28  |  57.3 KB  |  1,937 lines
  1. BEGIN {require 5.002;} # MakeMaker 5.17 was the last MakeMaker that was compatible with perl5.001m
  2.  
  3. package ExtUtils::MakeMaker;
  4.  
  5. $Version = $VERSION = "5.4301";
  6. $Version_OK = "5.17";    # Makefiles older than $Version_OK will die
  7.             # (Will be checked from MakeMaker version 4.13 onwards)
  8. ($Revision = substr(q$Revision: 1.222 $, 10)) =~ s/\s+$//;
  9.  
  10.  
  11.  
  12. require Exporter;
  13. use Config;
  14. use Carp ();
  15. #use FileHandle ();
  16.  
  17. use vars qw(
  18.  
  19.         @ISA @EXPORT @EXPORT_OK $AUTOLOAD
  20.         $ISA_TTY $Is_Mac $Is_OS2 $Is_VMS $Revision $Setup_done
  21.         $VERSION $Verbose $Version_OK %Config %Keep_after_flush
  22.         %MM_Sections %Prepend_dot_dot %Recognized_Att_Keys
  23.         @Get_from_Config @MM_Sections @Overridable @Parent
  24.  
  25.        );
  26. # use strict;
  27.  
  28. # &DynaLoader::mod2fname should be available to miniperl, thus 
  29. # should be a pseudo-builtin (cmp. os2.c).
  30. #eval {require DynaLoader;};
  31.  
  32. #
  33. # Set up the inheritance before we pull in the MM_* packages, because they
  34. # import variables and functions from here
  35. #
  36. @ISA = qw(Exporter);
  37. @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
  38. @EXPORT_OK = qw($VERSION &Version_check &neatvalue &mkbootstrap &mksymlists
  39.         $Version);
  40.         # $Version in mixed case will go away!
  41.  
  42. #
  43. # Dummy package MM inherits actual methods from OS-specific
  44. # default packages.  We use this intermediate package so
  45. # MY::XYZ->func() can call MM->func() and get the proper
  46. # default routine without having to know under what OS
  47. # it's running.
  48. #
  49. @MM::ISA = qw[ExtUtils::MM_Unix ExtUtils::Liblist ExtUtils::MakeMaker];
  50.  
  51. #
  52. # Setup dummy package:
  53. # MY exists for overriding methods to be defined within
  54. #
  55. {
  56.     package MY;
  57.     @MY::ISA = qw(MM);
  58. ###    sub AUTOLOAD { use Devel::Symdump; print Devel::Symdump->rnew->as_string; Carp::confess "hey why? $AUTOLOAD" }
  59.     package MM;
  60.     sub DESTROY {}
  61. }
  62.  
  63. # predeclare the package: we only load it via AUTOLOAD
  64. # but we have already mentioned it in @ISA
  65. package ExtUtils::Liblist;
  66.  
  67. package ExtUtils::MakeMaker;
  68. #
  69. # Now we can pull in the friends
  70. #
  71. $Is_VMS   = $^O eq 'VMS';
  72. $Is_OS2   = $^O eq 'os2';
  73. $Is_Mac   = $^O eq 'MacOS';
  74. $Is_Win32 = $^O eq 'MSWin32';
  75.  
  76. # This is for module authors to query, so they can enable 'CAPI' => 'TRUE'
  77. # in their Makefile.pl
  78. $CAPI_support = 1;
  79.  
  80. require ExtUtils::MM_Unix;
  81.  
  82. if ($Is_VMS) {
  83.     require ExtUtils::MM_VMS;
  84.     require VMS::Filespec; # is a noop as long as we require it within MM_VMS
  85. }
  86. if ($Is_OS2) {
  87.     require ExtUtils::MM_OS2;
  88. }
  89. if ($Is_Mac) {
  90.     require ExtUtils::MM_Mac;
  91. }
  92. if ($Is_Win32) {
  93.     require ExtUtils::MM_Win32;
  94. }
  95.  
  96. # The SelfLoader would bring a lot of overhead for MakeMaker, because
  97. # we know for sure we will use most of the autoloaded functions once
  98. # we have to use one of them. So we write our own loader
  99.  
  100. sub AUTOLOAD {
  101.     my $code;
  102.     if (defined fileno(DATA)) {
  103.     my $fh = select DATA;
  104.     my $o = $/;            # For future reads from the file.
  105.     $/ = "\n__END__\n";
  106.     $code = <DATA>;
  107.     $/ = $o;
  108.     select $fh;
  109.     close DATA;
  110.     eval $code;
  111.     if ($@) {
  112.         $@ =~ s/ at .*\n//;
  113.         Carp::croak $@;
  114.     }
  115.     } else {
  116.     warn "AUTOLOAD called unexpectedly for $AUTOLOAD"; 
  117.     }
  118.     defined(&$AUTOLOAD) or die "Myloader inconsistency error";
  119.     goto &$AUTOLOAD;
  120. }
  121.  
  122. # The only subroutine we do not SelfLoad is Version_Check because it's
  123. # called so often. Loading this minimum still requires 1.2 secs on my
  124. # Indy :-(
  125.  
  126. sub Version_check {
  127.     my($checkversion) = @_;
  128.     die "Your Makefile was built with ExtUtils::MakeMaker v $checkversion.
  129. Current Version is $ExtUtils::MakeMaker::VERSION. There have been considerable
  130. changes in the meantime.
  131. Please rerun 'perl Makefile.PL' to regenerate the Makefile.\n"
  132.     if $checkversion < $Version_OK;
  133.     printf STDOUT "%s %s %s %s.\n", "Makefile built with ExtUtils::MakeMaker v",
  134.     $checkversion, "Current Version is", $VERSION
  135.     unless $checkversion == $VERSION;
  136. }
  137.  
  138. sub warnhandler {
  139.     $_[0] =~ /^Use of uninitialized value/ && return;
  140.     $_[0] =~ /used only once/ && return;
  141.     $_[0] =~ /^Subroutine\s+[\w:]+\s+redefined/ && return;
  142.     warn @_;
  143. }
  144.  
  145. sub ExtUtils::MakeMaker::eval_in_subdirs ;
  146. sub ExtUtils::MakeMaker::eval_in_x ;
  147. sub ExtUtils::MakeMaker::full_setup ;
  148. sub ExtUtils::MakeMaker::writeMakefile ;
  149. sub ExtUtils::MakeMaker::new ;
  150. sub ExtUtils::MakeMaker::check_manifest ;
  151. sub ExtUtils::MakeMaker::parse_args ;
  152. sub ExtUtils::MakeMaker::check_hints ;
  153. sub ExtUtils::MakeMaker::mv_all_methods ;
  154. sub ExtUtils::MakeMaker::skipcheck ;
  155. sub ExtUtils::MakeMaker::flush ;
  156. sub ExtUtils::MakeMaker::mkbootstrap ;
  157. sub ExtUtils::MakeMaker::mksymlists ;
  158. sub ExtUtils::MakeMaker::neatvalue ;
  159. sub ExtUtils::MakeMaker::selfdocument ;
  160. sub ExtUtils::MakeMaker::WriteMakefile ;
  161. sub ExtUtils::MakeMaker::prompt ($;$) ;
  162.  
  163. 1;
  164.  
  165. __DATA__
  166.  
  167. package ExtUtils::MakeMaker;
  168.  
  169. sub WriteMakefile {
  170.     Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
  171.     local $SIG{__WARN__} = \&warnhandler;
  172.  
  173.     unless ($Setup_done++){
  174.     full_setup();
  175.     undef &ExtUtils::MakeMaker::full_setup; #safe memory
  176.     }
  177.     my %att = @_;
  178.     MM->new(\%att)->flush;
  179. }
  180.  
  181. sub prompt ($;$) {
  182.     my($mess,$def)=@_;
  183.     $ISA_TTY = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;    # Pipe?
  184.     Carp::confess("prompt function called without an argument") unless defined $mess;
  185.     my $dispdef = defined $def ? "[$def] " : " ";
  186.     $def = defined $def ? $def : "";
  187.     my $ans;
  188.     local $|=1;
  189.     print "$mess $dispdef";
  190.     if ($ISA_TTY) {
  191.     chomp($ans = <STDIN>);
  192.     } else {
  193.     print "$def\n";
  194.     }
  195.     return $ans || $def;
  196. }
  197.  
  198. sub eval_in_subdirs {
  199.     my($self) = @_;
  200.     my($dir);
  201.     use Cwd 'cwd';
  202.     my $pwd = cwd();
  203.  
  204.     foreach $dir (@{$self->{DIR}}){
  205.     my($abs) = $self->catdir($pwd,$dir);
  206.     $self->eval_in_x($abs);
  207.     }
  208.     chdir $pwd;
  209. }
  210.  
  211. sub eval_in_x {
  212.     my($self,$dir) = @_;
  213.     package main;
  214.     chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
  215. #    use FileHandle ();
  216. #    my $fh = new FileHandle;
  217. #    $fh->open("Makefile.PL") or Carp::carp("Couldn't open Makefile.PL in $dir");
  218.     local *FH;
  219.     open(FH,"Makefile.PL") or Carp::carp("Couldn't open Makefile.PL in $dir");
  220. #    my $eval = join "", <$fh>;
  221.     my $eval = join "", <FH>;
  222. #    $fh->close;
  223.     close FH;
  224.     eval $eval;
  225.     if ($@) {
  226. #       if ($@ =~ /prerequisites/) {
  227. #           die "MakeMaker WARNING: $@";
  228. #       } else {
  229. #           warn "WARNING from evaluation of $dir/Makefile.PL: $@";
  230. #       }
  231.     warn "WARNING from evaluation of $dir/Makefile.PL: $@";
  232.     }
  233. }
  234.  
  235. sub full_setup {
  236.     $Verbose ||= 0;
  237.     $^W=1;
  238.  
  239.     # package name for the classes into which the first object will be blessed
  240.     $PACKNAME = "PACK000";
  241.  
  242.     @Attrib_help = qw/
  243.  
  244.     AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION LICENSE_HREF CAPI
  245.     C CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
  246.     EXE_FILES EXCLUDE_EXT INCLUDE_EXT NO_VC FIRST_MAKEFILE FULLPERL H
  247.     INC INSTALLARCHLIB INSTALLBIN INSTALLDIRS INSTALLMAN1DIR
  248.     INSTALLMAN3DIR INSTALLPRIVLIB INSTALLSCRIPT INSTALLSITEARCH
  249.     INSTALLSITELIB INST_ARCHLIB INST_BIN INST_EXE INST_LIB
  250.     INST_MAN1DIR INST_MAN3DIR INST_SCRIPT LDFROM LIBPERL_A LIB LIBS
  251.     LINKTYPE MAKEAPERL MAKEFILE MAN1PODS MAN3PODS MAP_TARGET MYEXTLIB
  252.     NAME NEEDS_LINKING NOECHO NORECURS OBJECT OPTIMIZE PERL PERLMAINCC
  253.     PERL_ARCHLIB PERL_LIB PERL_SRC PERM_RW PERM_RWX
  254.     PL_FILES PM PMLIBDIRS PREFIX
  255.     PREREQ_PM SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
  256.     XS_VERSION clean depend dist dynamic_lib linkext macro realclean
  257.     tool_autosplit PPM_INSTALL_SCRIPT PPM_INSTALL_EXEC
  258.  
  259.     IMPORTS
  260.  
  261.     installpm
  262.     /;
  263.  
  264.     # IMPORTS is used under OS/2
  265.  
  266.     # ^^^ installpm is deprecated, will go about Summer 96
  267.  
  268.     # @Overridable is close to @MM_Sections but not identical.  The
  269.     # order is important. Many subroutines declare macros. These
  270.     # depend on each other. Let's try to collect the macros up front,
  271.     # then pasthru, then the rules.
  272.  
  273.     # MM_Sections are the sections we have to call explicitly
  274.     # in Overridable we have subroutines that are used indirectly
  275.  
  276.  
  277.     @MM_Sections = 
  278.     qw(
  279.  
  280.  post_initialize const_config constants tool_autosplit tool_xsubpp
  281.  tools_other dist macro depend cflags const_loadlibs const_cccmd
  282.  post_constants
  283.  
  284.  pasthru
  285.  
  286.  c_o xs_c xs_o top_targets linkext dlsyms dynamic dynamic_bs
  287.  dynamic_lib static static_lib manifypods processPL installbin subdirs
  288.  clean realclean dist_basics dist_core dist_dir dist_test dist_ci
  289.  install force perldepend makefile staticmake test ppd
  290.  
  291.       ); # loses section ordering
  292.  
  293.     @Overridable = @MM_Sections;
  294.     push @Overridable, qw[
  295.  
  296.  dir_target libscan makeaperl needs_linking perm_rw perm_rwx
  297.  subdir_x test_via_harness test_via_script
  298.  
  299.              ];
  300.  
  301.     push @MM_Sections, qw[
  302.  
  303.  pm_to_blib selfdocument
  304.  
  305.              ];
  306.  
  307.     # Postamble needs to be the last that was always the case
  308.     push @MM_Sections, "postamble";
  309.     push @Overridable, "postamble";
  310.  
  311.     # All sections are valid keys.
  312.     @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
  313.  
  314.     # we will use all these variables in the Makefile
  315.     @Get_from_Config = 
  316.     qw(
  317.        ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
  318.        lib_ext obj_ext osname osvers ranlib sitelibexp sitearchexp so exe_ext
  319.       );
  320.  
  321.     my $item;
  322.     foreach $item (@Attrib_help){
  323.     $Recognized_Att_Keys{$item} = 1;
  324.     }
  325.     foreach $item (@Get_from_Config) {
  326.     $Recognized_Att_Keys{uc $item} = $Config{$item};
  327.     print "Attribute '\U$item\E' => '$Config{$item}'\n"
  328.         if ($Verbose >= 2);
  329.     }
  330.  
  331.     #
  332.     # When we eval a Makefile.PL in a subdirectory, that one will ask
  333.     # us (the parent) for the values and will prepend "..", so that
  334.     # all files to be installed end up below OUR ./blib
  335.     #
  336.     %Prepend_dot_dot = 
  337.     qw(
  338.  
  339.        INST_BIN 1 INST_EXE 1 INST_LIB 1 INST_ARCHLIB 1 INST_SCRIPT
  340.        1 MAP_TARGET 1 INST_MAN1DIR 1 INST_MAN3DIR 1 PERL_SRC 1
  341.        PERL 1 FULLPERL 1
  342.  
  343.       );
  344.  
  345.     my @keep = qw/
  346.     NEEDS_LINKING HAS_LINK_CODE
  347.     /;
  348.     @Keep_after_flush{@keep} = (1) x @keep;
  349. }
  350.  
  351. sub writeMakefile {
  352.     die <<END;
  353.  
  354. The extension you are trying to build apparently is rather old and
  355. most probably outdated. We detect that from the fact, that a
  356. subroutine "writeMakefile" is called, and this subroutine is not
  357. supported anymore since about October 1994.
  358.  
  359. Please contact the author or look into CPAN (details about CPAN can be
  360. found in the FAQ and at http:/www.perl.com) for a more recent version
  361. of the extension. If you're really desperate, you can try to change
  362. the subroutine name from writeMakefile to WriteMakefile and rerun
  363. 'perl Makefile.PL', but you're most probably left alone, when you do
  364. so.
  365.  
  366. The MakeMaker team
  367.  
  368. END
  369. }
  370.  
  371. sub ExtUtils::MakeMaker::new {
  372.     my($class,$self) = @_;
  373.     my($key);
  374.  
  375.     print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
  376.     if (-f "MANIFEST" && ! -f "Makefile"){
  377.     check_manifest();
  378.     }
  379.  
  380.     $self = {} unless (defined $self);
  381.  
  382.     check_hints($self);
  383.  
  384.     my(%initial_att) = %$self; # record initial attributes
  385.  
  386.     my($prereq);
  387.     foreach $prereq (sort keys %{$self->{PREREQ_PM}}) {
  388.     my $eval = "use $prereq $self->{PREREQ_PM}->{$prereq}";
  389.     eval $eval;
  390.     if ($@){
  391.         warn "Warning: prerequisite $prereq $self->{PREREQ_PM}->{$prereq} not found";
  392. # Why is/was this 'delete' here?  We need PREREQ_PM later to make PPDs.
  393. #    } else {
  394. #        delete $self->{PREREQ_PM}{$prereq};
  395.     }
  396.     }
  397. #    if (@unsatisfied){
  398. #       unless (defined $ExtUtils::MakeMaker::useCPAN) {
  399. #           print qq{MakeMaker WARNING: prerequisites not found (@unsatisfied)
  400. # Please install these modules first and rerun 'perl Makefile.PL'.\n};
  401. #           if ($ExtUtils::MakeMaker::hasCPAN) {
  402. #           $ExtUtils::MakeMaker::useCPAN = prompt(qq{Should I try to use the CPAN module to fetch them for you?},"yes");
  403. #           } else {
  404. #           print qq{Hint: You may want to install the CPAN module to autofetch the needed modules\n};
  405. #           $ExtUtils::MakeMaker::useCPAN=0;
  406. #           }
  407. #       }
  408. #       if ($ExtUtils::MakeMaker::useCPAN) {
  409. #           require CPAN;
  410. #           CPAN->import(@unsatisfied);
  411. #       } else {
  412. #           die qq{prerequisites not found (@unsatisfied)};
  413. #       }
  414. #    warn qq{WARNING: prerequisites not found (@unsatisfied)};
  415. #    }
  416.  
  417.     if (defined $self->{CONFIGURE}) {
  418.     if (ref $self->{CONFIGURE} eq 'CODE') {
  419.         $self = { %$self, %{&{$self->{CONFIGURE}}}};
  420.     } else {
  421.         Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
  422.     }
  423.     }
  424.  
  425.     # This is for old Makefiles written pre 5.00, will go away
  426.     if ( Carp::longmess("") =~ /runsubdirpl/s ){
  427.     Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
  428.     }
  429.  
  430.     my $newclass = ++$PACKNAME;
  431.     {
  432. #    no strict;
  433.     print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
  434.     mv_all_methods("MY",$newclass);
  435.     bless $self, $newclass;
  436.     push @Parent, $self;
  437.     @{"$newclass\:\:ISA"} = 'MM';
  438.     }
  439.  
  440.     if (defined $Parent[-2]){
  441.     $self->{PARENT} = $Parent[-2];
  442.     my $key;
  443.     for $key (keys %Prepend_dot_dot) {
  444.         next unless defined $self->{PARENT}{$key};
  445.         $self->{$key} = $self->{PARENT}{$key};
  446.         # PERL and FULLPERL may be command verbs instead of full
  447.         # file specifications under VMS.  If so, don't turn them
  448.         # into a filespec.
  449.         $self->{$key} = $self->catdir("..",$self->{$key})
  450.         unless $self->file_name_is_absolute($self->{$key})
  451.         || ($^O eq 'VMS' and ($key =~ /PERL$/ && $self->{$key} =~ /^[\w\-\$]+$/));
  452.     }
  453.     $self->{PARENT}->{CHILDREN}->{$newclass} = $self if $self->{PARENT};
  454.     } else {
  455.     parse_args($self,@ARGV);
  456.     }
  457.  
  458.     $self->{NAME} ||= $self->guess_name;
  459.  
  460.     ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
  461.  
  462.     $self->init_main();
  463.  
  464.     if (! $self->{PERL_SRC} ) {
  465.     my($pthinks) = $self->canonpath($INC{'Config.pm'});
  466.     my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
  467.     $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
  468.     if ($pthinks ne $cthinks &&
  469.         !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
  470.             print "Have $pthinks expected $cthinks\n";
  471.         if ($Is_Win32) {
  472.         $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
  473.         }
  474.         else {
  475.         $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
  476.         }
  477.         print STDOUT <<END;
  478. Your perl and your Config.pm seem to have different ideas about the architecture
  479. they are running on.
  480. Perl thinks: [$pthinks]
  481. Config says: [$Config{archname}]
  482. This may or may not cause problems. Please check your installation of perl if you
  483. have problems building this extension.
  484. END
  485.     }
  486.     }
  487.  
  488.     $self->init_dirscan();
  489.     $self->init_others();
  490.  
  491.     push @{$self->{RESULT}}, <<END;
  492. # This Makefile is for the $self->{NAME} extension to perl.
  493. #
  494. # It was generated automatically by MakeMaker version
  495. # $VERSION (Revision: $Revision) from the contents of
  496. # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
  497. #
  498. #    ANY CHANGES MADE HERE WILL BE LOST!
  499. #
  500. #   MakeMaker Parameters:
  501. END
  502.  
  503.     foreach $key (sort keys %initial_att){
  504.     my($v) = neatvalue($initial_att{$key});
  505.     $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
  506.     $v =~ tr/\n/ /s;
  507.     push @{$self->{RESULT}}, "#    $key => $v";
  508.     }
  509.  
  510.     # SGI-specific: turn off parallel-make
  511.     push @{$self->{RESULT}}, "\n# SGI: no parallel make\n.MAKEFLAGS: -J 1";
  512.  
  513.     # turn the SKIP array into a SKIPHASH hash
  514.     my (%skip,$skip);
  515.     for $skip (@{$self->{SKIP} || []}) {
  516.     $self->{SKIPHASH}{$skip} = 1;
  517.     }
  518.     delete $self->{SKIP}; # free memory
  519.  
  520.     if ($self->{PARENT}) {
  521.     for (qw/install dist dist_basics dist_core dist_dir dist_test dist_ci/) {
  522.         $self->{SKIPHASH}{$_} = 1;
  523.     }
  524.     }
  525.  
  526.     # We run all the subdirectories now. They don't have much to query
  527.     # from the parent, but the parent has to query them: if they need linking!
  528.     unless ($self->{NORECURS}) {
  529.     $self->eval_in_subdirs if @{$self->{DIR}};
  530.     }
  531.  
  532.     my $section;
  533.     foreach $section ( @MM_Sections ){
  534.     print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
  535.     my($skipit) = $self->skipcheck($section);
  536.     if ($skipit){
  537.         push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
  538.     } else {
  539.         my(%a) = %{$self->{$section} || {}};
  540.         push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
  541.         push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
  542.         push @{$self->{RESULT}}, $self->nicetext($self->$section( %a ));
  543.     }
  544.     }
  545.  
  546.     push @{$self->{RESULT}}, "\n# End.";
  547.     pop @Parent;
  548.  
  549.     $self;
  550. }
  551.  
  552. sub WriteEmptyMakefile {
  553.   if (-f 'Makefile.old') {
  554.     chmod 0666, 'Makefile.old';
  555.     unlink 'Makefile.old' or warn "unlink Makefile.old: $!";
  556.   }
  557.   rename 'Makefile', 'Makefile.old' or warn "rename Makefile Makefile.old: $!"
  558.     if -f 'Makefile';
  559.   open MF, '> Makefile' or die "open Makefile for write: $!";
  560.   print MF <<'EOP';
  561. all:
  562.  
  563. clean:
  564.  
  565. install:
  566.  
  567. makemakerdflt:
  568.  
  569. test:
  570.  
  571. EOP
  572.   close MF or die "close Makefile for write: $!";
  573. }
  574.  
  575. sub check_manifest {
  576.     print STDOUT "Checking if your kit is complete...\n";
  577.     require ExtUtils::Manifest;
  578.     $ExtUtils::Manifest::Quiet=$ExtUtils::Manifest::Quiet=1; #avoid warning
  579.     my(@missed)=ExtUtils::Manifest::manicheck();
  580.     if (@missed){
  581.     print STDOUT "Warning: the following files are missing in your kit:\n";
  582.     print "\t", join "\n\t", @missed;
  583.     print STDOUT "\n";
  584.     print STDOUT "Please inform the author.\n";
  585.     } else {
  586.     print STDOUT "Looks good\n";
  587.     }
  588. }
  589.  
  590. sub parse_args{
  591.     my($self, @args) = @_;
  592.     foreach (@args){
  593.     unless (m/(.*?)=(.*)/){
  594.         help(),exit 1 if m/^help$/;
  595.         ++$Verbose if m/^verb/;
  596.         next;
  597.     }
  598.     my($name, $value) = ($1, $2);
  599.     if ($value =~ m/^~(\w+)?/){ # tilde with optional username
  600.         $value =~ s [^~(\w*)]
  601.         [$1 ?
  602.          ((getpwnam($1))[7] || "~$1") :
  603.          (getpwuid($>))[7]
  604.          ]ex;
  605.     }
  606.     $self->{uc($name)} = $value;
  607.     }
  608.  
  609.     # catch old-style 'potential_libs' and inform user how to 'upgrade'
  610.     if (defined $self->{potential_libs}){
  611.     my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
  612.     if ($self->{potential_libs}){
  613.         print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
  614.     } else {
  615.         print STDOUT "$msg deleted.\n";
  616.     }
  617.     $self->{LIBS} = [$self->{potential_libs}];
  618.     delete $self->{potential_libs};
  619.     }
  620.     # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
  621.     if (defined $self->{ARMAYBE}){
  622.     my($armaybe) = $self->{ARMAYBE};
  623.     print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
  624.             "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
  625.     my(%dl) = %{$self->{dynamic_lib} || {}};
  626.     $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
  627.     delete $self->{ARMAYBE};
  628.     }
  629.     if (defined $self->{LDTARGET}){
  630.     print STDOUT "LDTARGET should be changed to LDFROM\n";
  631.     $self->{LDFROM} = $self->{LDTARGET};
  632.     delete $self->{LDTARGET};
  633.     }
  634.     # Turn a DIR argument on the command line into an array
  635.     if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
  636.     # So they can choose from the command line, which extensions they want
  637.     # the grep enables them to have some colons too much in case they
  638.     # have to build a list with the shell
  639.     $self->{DIR} = [grep $_, split ":", $self->{DIR}];
  640.     }
  641.     # Turn a INCLUDE_EXT argument on the command line into an array
  642.     if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
  643.     $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
  644.     }
  645.     # Turn a EXCLUDE_EXT argument on the command line into an array
  646.     if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
  647.     $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
  648.     }
  649.     my $mmkey;
  650.     foreach $mmkey (sort keys %$self){
  651.     print STDOUT "    $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
  652.     print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
  653.         unless exists $Recognized_Att_Keys{$mmkey};
  654.     }
  655.     $| = 1 if $Verbose;
  656. }
  657.  
  658. sub check_hints {
  659.     my($self) = @_;
  660.     # We allow extension-specific hints files.
  661.  
  662.     return unless -d "hints";
  663.  
  664.     # First we look for the best hintsfile we have
  665.     my(@goodhints);
  666.     my($hint)="${^O}_$Config{osvers}";
  667.     $hint =~ s/\./_/g;
  668.     $hint =~ s/_$//;
  669.     return unless $hint;
  670.  
  671.     # Also try without trailing minor version numbers.
  672.     while (1) {
  673.     last if -f "hints/$hint.pl";      # found
  674.     } continue {
  675.     last unless $hint =~ s/_[^_]*$//; # nothing to cut off
  676.     }
  677.     return unless -f "hints/$hint.pl";    # really there
  678.  
  679.     # execute the hintsfile:
  680. #    use FileHandle ();
  681. #    my $fh = new FileHandle;
  682. #    $fh->open("hints/$hint.pl");
  683.     local *FH;
  684.     open(FH,"hints/$hint.pl");
  685. #    @goodhints = <$fh>;
  686.     @goodhints = <FH>;
  687. #    $fh->close;
  688.     close FH;
  689.     print STDOUT "Processing hints file hints/$hint.pl\n";
  690.     eval join('',@goodhints);
  691.     print STDOUT $@ if $@;
  692. }
  693.  
  694. sub mv_all_methods {
  695.     my($from,$to) = @_;
  696.     my($method);
  697.     my($symtab) = \%{"${from}::"};
  698. #    no strict;
  699.  
  700.     # Here you see the *current* list of methods that are overridable
  701.     # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
  702.     # still trying to reduce the list to some reasonable minimum --
  703.     # because I want to make it easier for the user. A.K.
  704.  
  705.     foreach $method (@Overridable) {
  706.  
  707.     # We cannot say "next" here. Nick might call MY->makeaperl
  708.     # which isn't defined right now
  709.  
  710.     # Above statement was written at 4.23 time when Tk-b8 was
  711.     # around. As Tk-b9 only builds with 5.002something and MM 5 is
  712.     # standard, we try to enable the next line again. It was
  713.     # commented out until MM 5.23
  714.  
  715.     next unless defined &{"${from}::$method"};
  716.  
  717.     *{"${to}::$method"} = \&{"${from}::$method"};
  718.  
  719.     # delete would do, if we were sure, nobody ever called
  720.     # MY->makeaperl directly
  721.     
  722.     # delete $symtab->{$method};
  723.     
  724.     # If we delete a method, then it will be undefined and cannot
  725.     # be called.  But as long as we have Makefile.PLs that rely on
  726.     # %MY:: being intact, we have to fill the hole with an
  727.     # inheriting method:
  728.  
  729.     eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
  730.     }
  731.  
  732.     # We have to clean out %INC also, because the current directory is
  733.     # changed frequently and Graham Barr prefers to get his version
  734.     # out of a History.pl file which is "required" so woudn't get
  735.     # loaded again in another extension requiring a History.pl
  736.  
  737.     # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
  738.     # to core dump in the middle of a require statement. The required
  739.     # file was Tk/MMutil.pm.  The consequence is, we have to be
  740.     # extremely careful when we try to give perl a reason to reload a
  741.     # library with same name.  The workaround prefers to drop nothing
  742.     # from %INC and teach the writers not to use such libraries.
  743.  
  744. #    my $inc;
  745. #    foreach $inc (keys %INC) {
  746. #    #warn "***$inc*** deleted";
  747. #    delete $INC{$inc};
  748. #    }
  749. }
  750.  
  751. sub skipcheck {
  752.     my($self) = shift;
  753.     my($section) = @_;
  754.     if ($section eq 'dynamic') {
  755.     print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
  756.     "in skipped section 'dynamic_bs'\n"
  757.             if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
  758.         print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
  759.     "in skipped section 'dynamic_lib'\n"
  760.             if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
  761.     }
  762.     if ($section eq 'dynamic_lib') {
  763.         print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
  764.     "targets in skipped section 'dynamic_bs'\n"
  765.             if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
  766.     }
  767.     if ($section eq 'static') {
  768.         print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
  769.     "in skipped section 'static_lib'\n"
  770.             if $self->{SKIPHASH}{static_lib} && $Verbose;
  771.     }
  772.     return 'skipped' if $self->{SKIPHASH}{$section};
  773.     return '';
  774. }
  775.  
  776. sub flush {
  777.     my $self = shift;
  778.     my($chunk);
  779. #    use FileHandle ();
  780. #    my $fh = new FileHandle;
  781.     local *FH;
  782.     print STDOUT "Writing $self->{MAKEFILE} for $self->{NAME}\n";
  783.  
  784.     unlink($self->{MAKEFILE}, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : '');
  785. #    $fh->open(">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
  786.     open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
  787.  
  788.     for $chunk (@{$self->{RESULT}}) {
  789. #    print $fh "$chunk\n";
  790.     print FH "$chunk\n";
  791.     }
  792.  
  793. #    $fh->close;
  794.     close FH;
  795.     my($finalname) = $self->{MAKEFILE};
  796.     rename("MakeMaker.tmp", $finalname);
  797.     chmod 0644, $finalname unless $Is_VMS;
  798.  
  799.     if ($self->{PARENT}) {
  800.     foreach (keys %$self) { # safe memory
  801.         delete $self->{$_} unless $Keep_after_flush{$_};
  802.     }
  803.     }
  804.  
  805.     system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
  806. }
  807.  
  808. # The following mkbootstrap() is only for installations that are calling
  809. # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
  810. # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
  811. sub mkbootstrap {
  812.     die <<END;
  813. !!! Your Makefile has been built such a long time ago, !!!
  814. !!! that is unlikely to work with current MakeMaker.   !!!
  815. !!! Please rebuild your Makefile                       !!!
  816. END
  817. }
  818.  
  819. # Ditto for mksymlists() as of MakeMaker 5.17
  820. sub mksymlists {
  821.     die <<END;
  822. !!! Your Makefile has been built such a long time ago, !!!
  823. !!! that is unlikely to work with current MakeMaker.   !!!
  824. !!! Please rebuild your Makefile                       !!!
  825. END
  826. }
  827.  
  828. sub neatvalue {
  829.     my($v) = @_;
  830.     return "undef" unless defined $v;
  831.     my($t) = ref $v;
  832.     return "q[$v]" unless $t;
  833.     if ($t eq 'ARRAY') {
  834.     my(@m, $elem, @neat);
  835.     push @m, "[";
  836.     foreach $elem (@$v) {
  837.         push @neat, "q[$elem]";
  838.     }
  839.     push @m, join ", ", @neat;
  840.     push @m, "]";
  841.     return join "", @m;
  842.     }
  843.     return "$v" unless $t eq 'HASH';
  844.     my(@m, $key, $val);
  845.     while (($key,$val) = each %$v){
  846.     last unless defined $key; # cautious programming in case (undef,undef) is true
  847.     push(@m,"$key=>".neatvalue($val)) ;
  848.     }
  849.     return "{ ".join(', ',@m)." }";
  850. }
  851.  
  852. sub selfdocument {
  853.     my($self) = @_;
  854.     my(@m);
  855.     if ($Verbose){
  856.     push @m, "\n# Full list of MakeMaker attribute values:";
  857.     foreach $key (sort keys %$self){
  858.         next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
  859.         my($v) = neatvalue($self->{$key});
  860.         $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
  861.         $v =~ tr/\n/ /s;
  862.         push @m, "#    $key => $v";
  863.     }
  864.     }
  865.     join "\n", @m;
  866. }
  867.  
  868. package ExtUtils::MakeMaker;
  869. 1;
  870.  
  871. __END__
  872.  
  873. =head1 NAME
  874.  
  875. ExtUtils::MakeMaker - create an extension Makefile
  876.  
  877. =head1 SYNOPSIS
  878.  
  879. C<use ExtUtils::MakeMaker;>
  880.  
  881. C<WriteMakefile( ATTRIBUTE =E<gt> VALUE [, ...] );>
  882.  
  883. which is really
  884.  
  885. C<MM-E<gt>new(\%att)-E<gt>flush;>
  886.  
  887. =head1 DESCRIPTION
  888.  
  889. This utility is designed to write a Makefile for an extension module
  890. from a Makefile.PL. It is based on the Makefile.SH model provided by
  891. Andy Dougherty and the perl5-porters.
  892.  
  893. It splits the task of generating the Makefile into several subroutines
  894. that can be individually overridden.  Each subroutine returns the text
  895. it wishes to have written to the Makefile.
  896.  
  897. MakeMaker is object oriented. Each directory below the current
  898. directory that contains a Makefile.PL. Is treated as a separate
  899. object. This makes it possible to write an unlimited number of
  900. Makefiles with a single invocation of WriteMakefile().
  901.  
  902. =head2 How To Write A Makefile.PL
  903.  
  904. The short answer is: Don't.
  905.  
  906.         Always begin with h2xs.
  907.         Always begin with h2xs!
  908.         ALWAYS BEGIN WITH H2XS!
  909.  
  910. even if you're not building around a header file, and even if you
  911. don't have an XS component.
  912.  
  913. Run h2xs(1) before you start thinking about writing a module. For so
  914. called pm-only modules that consist of C<*.pm> files only, h2xs has
  915. the C<-X> switch. This will generate dummy files of all kinds that are
  916. useful for the module developer.
  917.  
  918. The medium answer is:
  919.  
  920.     use ExtUtils::MakeMaker;
  921.     WriteMakefile( NAME => "Foo::Bar" );
  922.  
  923. The long answer is the rest of the manpage :-)
  924.  
  925. =head2 Default Makefile Behaviour
  926.  
  927. The generated Makefile enables the user of the extension to invoke
  928.  
  929.   perl Makefile.PL # optionally "perl Makefile.PL verbose"
  930.   make
  931.   make test        # optionally set TEST_VERBOSE=1
  932.   make install     # See below
  933.  
  934. The Makefile to be produced may be altered by adding arguments of the
  935. form C<KEY=VALUE>. E.g.
  936.  
  937.   perl Makefile.PL PREFIX=/tmp/myperl5
  938.  
  939. Other interesting targets in the generated Makefile are
  940.  
  941.   make config     # to check if the Makefile is up-to-date
  942.   make clean      # delete local temp files (Makefile gets renamed)
  943.   make realclean  # delete derived files (including ./blib)
  944.   make ci         # check in all the files in the MANIFEST file
  945.   make dist       # see below the Distribution Support section
  946.  
  947. =head2 make test
  948.  
  949. MakeMaker checks for the existence of a file named F<test.pl> in the
  950. current directory and if it exists it adds commands to the test target
  951. of the generated Makefile that will execute the script with the proper
  952. set of perl C<-I> options.
  953.  
  954. MakeMaker also checks for any files matching glob("t/*.t"). It will
  955. add commands to the test target of the generated Makefile that execute
  956. all matching files via the L<Test::Harness> module with the C<-I>
  957. switches set correctly.
  958.  
  959. =head2 make testdb
  960.  
  961. A useful variation of the above is the target C<testdb>. It runs the
  962. test under the Perl debugger (see L<perldebug>). If the file
  963. F<test.pl> exists in the current directory, it is used for the test.
  964.  
  965. If you want to debug some other testfile, set C<TEST_FILE> variable
  966. thusly:
  967.  
  968.   make testdb TEST_FILE=t/mytest.t
  969.  
  970. By default the debugger is called using C<-d> option to perl. If you
  971. want to specify some other option, set C<TESTDB_SW> variable:
  972.  
  973.   make testdb TESTDB_SW=-Dx
  974.  
  975. =head2 make install
  976.  
  977. make alone puts all relevant files into directories that are named by
  978. the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR, and
  979. INST_MAN3DIR. All these default to something below ./blib if you are
  980. I<not> building below the perl source directory. If you I<are>
  981. building below the perl source, INST_LIB and INST_ARCHLIB default to
  982.  ../../lib, and INST_SCRIPT is not defined.
  983.  
  984. The I<install> target of the generated Makefile copies the files found
  985. below each of the INST_* directories to their INSTALL*
  986. counterparts. Which counterparts are chosen depends on the setting of
  987. INSTALLDIRS according to the following table:
  988.  
  989.                       INSTALLDIRS set to
  990.                               perl                 site
  991.  
  992.     INST_ARCHLIB    INSTALLARCHLIB    INSTALLSITEARCH
  993.     INST_LIB        INSTALLPRIVLIB    INSTALLSITELIB
  994.     INST_BIN                  INSTALLBIN
  995.     INST_SCRIPT              INSTALLSCRIPT
  996.     INST_MAN1DIR             INSTALLMAN1DIR
  997.     INST_MAN3DIR             INSTALLMAN3DIR
  998.  
  999. The INSTALL... macros in turn default to their %Config
  1000. ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
  1001.  
  1002. You can check the values of these variables on your system with
  1003.  
  1004.     perl '-V:install.*'
  1005.  
  1006. And to check the sequence in which the library directories are
  1007. searched by perl, run
  1008.  
  1009.     perl -le 'print join $/, @INC'
  1010.  
  1011.  
  1012. =head2 PREFIX and LIB attribute
  1013.  
  1014. PREFIX and LIB can be used to set several INSTALL* attributes in one
  1015. go. The quickest way to install a module in a non-standard place might
  1016. be
  1017.  
  1018.     perl Makefile.PL LIB=~/lib
  1019.  
  1020. This will install the module's architecture-independent files into
  1021. ~/lib, the architecture-dependent files into ~/lib/$archname/auto.
  1022.  
  1023. Another way to specify many INSTALL directories with a single
  1024. parameter is PREFIX.
  1025.  
  1026.     perl Makefile.PL PREFIX=~
  1027.  
  1028. This will replace the string specified by $Config{prefix} in all
  1029. $Config{install*} values.
  1030.  
  1031. Note, that in both cases the tilde expansion is done by MakeMaker, not
  1032. by perl by default, nor by make. Conflicts between parmeters LIB,
  1033. PREFIX and the various INSTALL* arguments are resolved so that 
  1034. XXX
  1035.  
  1036. If the user has superuser privileges, and is not working on AFS
  1037. (Andrew File System) or relatives, then the defaults for
  1038. INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSCRIPT, etc. will be appropriate,
  1039. and this incantation will be the best:
  1040.  
  1041.     perl Makefile.PL; make; make test
  1042.     make install
  1043.  
  1044. make install per default writes some documentation of what has been
  1045. done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
  1046. can be bypassed by calling make pure_install.
  1047.  
  1048. =head2 AFS users
  1049.  
  1050. will have to specify the installation directories as these most
  1051. probably have changed since perl itself has been installed. They will
  1052. have to do this by calling
  1053.  
  1054.     perl Makefile.PL INSTALLSITELIB=/afs/here/today \
  1055.     INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
  1056.     make
  1057.  
  1058. Be careful to repeat this procedure every time you recompile an
  1059. extension, unless you are sure the AFS installation directories are
  1060. still valid.
  1061.  
  1062. =head2 Static Linking of a new Perl Binary
  1063.  
  1064. An extension that is built with the above steps is ready to use on
  1065. systems supporting dynamic loading. On systems that do not support
  1066. dynamic loading, any newly created extension has to be linked together
  1067. with the available resources. MakeMaker supports the linking process
  1068. by creating appropriate targets in the Makefile whenever an extension
  1069. is built. You can invoke the corresponding section of the makefile with
  1070.  
  1071.     make perl
  1072.  
  1073. That produces a new perl binary in the current directory with all
  1074. extensions linked in that can be found in INST_ARCHLIB , SITELIBEXP,
  1075. and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
  1076. UNIX, this is called Makefile.aperl (may be system dependent). If you
  1077. want to force the creation of a new perl, it is recommended, that you
  1078. delete this Makefile.aperl, so the directories are searched-through
  1079. for linkable libraries again.
  1080.  
  1081. The binary can be installed into the directory where perl normally
  1082. resides on your machine with
  1083.  
  1084.     make inst_perl
  1085.  
  1086. To produce a perl binary with a different name than C<perl>, either say
  1087.  
  1088.     perl Makefile.PL MAP_TARGET=myperl
  1089.     make myperl
  1090.     make inst_perl
  1091.  
  1092. or say
  1093.  
  1094.     perl Makefile.PL
  1095.     make myperl MAP_TARGET=myperl
  1096.     make inst_perl MAP_TARGET=myperl
  1097.  
  1098. In any case you will be prompted with the correct invocation of the
  1099. C<inst_perl> target that installs the new binary into INSTALLBIN.
  1100.  
  1101. make inst_perl per default writes some documentation of what has been
  1102. done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
  1103. can be bypassed by calling make pure_inst_perl.
  1104.  
  1105. Warning: the inst_perl: target will most probably overwrite your
  1106. existing perl binary. Use with care!
  1107.  
  1108. Sometimes you might want to build a statically linked perl although
  1109. your system supports dynamic loading. In this case you may explicitly
  1110. set the linktype with the invocation of the Makefile.PL or make:
  1111.  
  1112.     perl Makefile.PL LINKTYPE=static    # recommended
  1113.  
  1114. or
  1115.  
  1116.     make LINKTYPE=static                # works on most systems
  1117.  
  1118. =head2 Determination of Perl Library and Installation Locations
  1119.  
  1120. MakeMaker needs to know, or to guess, where certain things are
  1121. located.  Especially INST_LIB and INST_ARCHLIB (where to put the files
  1122. during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
  1123. existing modules from), and PERL_INC (header files and C<libperl*.*>).
  1124.  
  1125. Extensions may be built either using the contents of the perl source
  1126. directory tree or from the installed perl library. The recommended way
  1127. is to build extensions after you have run 'make install' on perl
  1128. itself. You can do that in any directory on your hard disk that is not
  1129. below the perl source tree. The support for extensions below the ext
  1130. directory of the perl distribution is only good for the standard
  1131. extensions that come with perl.
  1132.  
  1133. If an extension is being built below the C<ext/> directory of the perl
  1134. source then MakeMaker will set PERL_SRC automatically (e.g.,
  1135. C<../..>).  If PERL_SRC is defined and the extension is recognized as
  1136. a standard extension, then other variables default to the following:
  1137.  
  1138.   PERL_INC     = PERL_SRC
  1139.   PERL_LIB     = PERL_SRC/lib
  1140.   PERL_ARCHLIB = PERL_SRC/lib
  1141.   INST_LIB     = PERL_LIB
  1142.   INST_ARCHLIB = PERL_ARCHLIB
  1143.  
  1144. If an extension is being built away from the perl source then MakeMaker
  1145. will leave PERL_SRC undefined and default to using the installed copy
  1146. of the perl library. The other variables default to the following:
  1147.  
  1148.   PERL_INC     = $archlibexp/CORE
  1149.   PERL_LIB     = $privlibexp
  1150.   PERL_ARCHLIB = $archlibexp
  1151.   INST_LIB     = ./blib/lib
  1152.   INST_ARCHLIB = ./blib/arch
  1153.  
  1154. If perl has not yet been installed then PERL_SRC can be defined on the
  1155. command line as shown in the previous section.
  1156.  
  1157.  
  1158. =head2 Which architecture dependent directory?
  1159.  
  1160. If you don't want to keep the defaults for the INSTALL* macros,
  1161. MakeMaker helps you to minimize the typing needed: the usual
  1162. relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
  1163. by Configure at perl compilation time. MakeMaker supports the user who
  1164. sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
  1165. then MakeMaker defaults the latter to be the same subdirectory of
  1166. INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
  1167. otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
  1168. for INSTALLSITELIB and INSTALLSITEARCH.
  1169.  
  1170. MakeMaker gives you much more freedom than needed to configure
  1171. internal variables and get different results. It is worth to mention,
  1172. that make(1) also lets you configure most of the variables that are
  1173. used in the Makefile. But in the majority of situations this will not
  1174. be necessary, and should only be done, if the author of a package
  1175. recommends it (or you know what you're doing).
  1176.  
  1177. =head2 Using Attributes and Parameters
  1178.  
  1179. The following attributes can be specified as arguments to WriteMakefile()
  1180. or as NAME=VALUE pairs on the command line:
  1181.  
  1182. =cut
  1183.  
  1184. # The following "=item C" is used by the attrib_help routine
  1185. # likewise the "=back" below. So be careful when changing it!
  1186.  
  1187. =over 2
  1188.  
  1189. =item C
  1190.  
  1191. Ref to array of *.c file names. Initialised from a directory scan
  1192. and the values portion of the XS attribute hash. This is not
  1193. currently used by MakeMaker but may be handy in Makefile.PLs.
  1194.  
  1195. =item CCFLAGS
  1196.  
  1197. String that will be included in the compiler call command line between
  1198. the arguments INC and OPTIMIZE.
  1199.  
  1200. =item CONFIG
  1201.  
  1202. Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
  1203. config.sh. MakeMaker will add to CONFIG the following values anyway:
  1204. ar
  1205. cc
  1206. cccdlflags
  1207. ccdlflags
  1208. dlext
  1209. dlsrc
  1210. ld
  1211. lddlflags
  1212. ldflags
  1213. libc
  1214. lib_ext
  1215. obj_ext
  1216. ranlib
  1217. sitelibexp
  1218. sitearchexp
  1219. so
  1220.  
  1221. =item CONFIGURE
  1222.  
  1223. CODE reference. The subroutine should return a hash reference. The
  1224. hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
  1225. be determined by some evaluation method.
  1226.  
  1227. =item DEFINE
  1228.  
  1229. Something like C<"-DHAVE_UNISTD_H">
  1230.  
  1231. =item DIR
  1232.  
  1233. Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
  1234. ] in ext/SDBM_File
  1235.  
  1236. =item DISTNAME
  1237.  
  1238. Your name for distributing the package (by tar file). This defaults to
  1239. NAME above.
  1240.  
  1241. =item DL_FUNCS
  1242.  
  1243. Hashref of symbol names for routines to be made available as
  1244. universal symbols.  Each key/value pair consists of the package name
  1245. and an array of routine names in that package.  Used only under AIX
  1246. (export lists) and VMS (linker options) at present.  The routine
  1247. names supplied will be expanded in the same way as XSUB names are
  1248. expanded by the XS() macro.  Defaults to
  1249.  
  1250.   {"$(NAME)" => ["boot_$(NAME)" ] }
  1251.  
  1252. e.g.
  1253.  
  1254.   {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
  1255.    "NetconfigPtr" => [ 'DESTROY'] }
  1256.  
  1257. =item DL_VARS
  1258.  
  1259. Array of symbol names for variables to be made available as
  1260. universal symbols.  Used only under AIX (export lists) and VMS
  1261. (linker options) at present.  Defaults to [].  (e.g. [ qw(
  1262. Foo_version Foo_numstreams Foo_tree ) ])
  1263.  
  1264. =item EXCLUDE_EXT
  1265.  
  1266. Array of extension names to exclude when doing a static build.  This
  1267. is ignored if INCLUDE_EXT is present.  Consult INCLUDE_EXT for more
  1268. details.  (e.g.  [ qw( Socket POSIX ) ] )
  1269.  
  1270. This attribute may be most useful when specified as a string on the
  1271. commandline:  perl Makefile.PL EXCLUDE_EXT='Socket Safe'
  1272.  
  1273. =item EXE_FILES
  1274.  
  1275. Ref to array of executable files. The files will be copied to the
  1276. INST_SCRIPT directory. Make realclean will delete them from there
  1277. again.
  1278.  
  1279. =item NO_VC
  1280.  
  1281. In general any generated Makefile checks for the current version of
  1282. MakeMaker and the version the Makefile was built under. If NO_VC is
  1283. set, the version check is neglected. Do not write this into your
  1284. Makefile.PL, use it interactively instead.
  1285.  
  1286. =item FIRST_MAKEFILE
  1287.  
  1288. The name of the Makefile to be produced. Defaults to the contents of
  1289. MAKEFILE, but can be overridden. This is used for the second Makefile
  1290. that will be produced for the MAP_TARGET.
  1291.  
  1292. =item FULLPERL
  1293.  
  1294. Perl binary able to run this extension.
  1295.  
  1296. =item H
  1297.  
  1298. Ref to array of *.h file names. Similar to C.
  1299.  
  1300. =item IMPORTS
  1301.  
  1302. IMPORTS is only used on OS/2.
  1303.  
  1304. =item INC
  1305.  
  1306. Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
  1307.  
  1308. =item INCLUDE_EXT
  1309.  
  1310. Array of extension names to be included when doing a static build.
  1311. MakeMaker will normally build with all of the installed extensions when
  1312. doing a static build, and that is usually the desired behavior.  If
  1313. INCLUDE_EXT is present then MakeMaker will build only with those extensions
  1314. which are explicitly mentioned. (e.g.  [ qw( Socket POSIX ) ])
  1315.  
  1316. It is not necessary to mention DynaLoader or the current extension when
  1317. filling in INCLUDE_EXT.  If the INCLUDE_EXT is mentioned but is empty then
  1318. only DynaLoader and the current extension will be included in the build.
  1319.  
  1320. This attribute may be most useful when specified as a string on the
  1321. commandline:  perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
  1322.  
  1323. =item INSTALLARCHLIB
  1324.  
  1325. Used by 'make install', which copies files from INST_ARCHLIB to this
  1326. directory if INSTALLDIRS is set to perl.
  1327.  
  1328. =item INSTALLBIN
  1329.  
  1330. Directory to install binary files (e.g. tkperl) into.
  1331.  
  1332. =item INSTALLDIRS
  1333.  
  1334. Determines which of the two sets of installation directories to
  1335. choose: installprivlib and installarchlib versus installsitelib and
  1336. installsitearch. The first pair is chosen with INSTALLDIRS=perl, the
  1337. second with INSTALLDIRS=site. Default is site.
  1338.  
  1339. =item INSTALLMAN1DIR
  1340.  
  1341. This directory gets the man pages at 'make install' time. Defaults to
  1342. $Config{installman1dir}.
  1343.  
  1344. =item INSTALLMAN3DIR
  1345.  
  1346. This directory gets the man pages at 'make install' time. Defaults to
  1347. $Config{installman3dir}.
  1348.  
  1349. =item INSTALLPRIVLIB
  1350.  
  1351. Used by 'make install', which copies files from INST_LIB to this
  1352. directory if INSTALLDIRS is set to perl.
  1353.  
  1354. =item INSTALLSCRIPT
  1355.  
  1356. Used by 'make install' which copies files from INST_SCRIPT to this
  1357. directory.
  1358.  
  1359. =item INSTALLSITELIB
  1360.  
  1361. Used by 'make install', which copies files from INST_LIB to this
  1362. directory if INSTALLDIRS is set to site (default).
  1363.  
  1364. =item INSTALLSITEARCH
  1365.  
  1366. Used by 'make install', which copies files from INST_ARCHLIB to this
  1367. directory if INSTALLDIRS is set to site (default).
  1368.  
  1369. =item INST_ARCHLIB
  1370.  
  1371. Same as INST_LIB for architecture dependent files.
  1372.  
  1373. =item INST_BIN
  1374.  
  1375. Directory to put real binary files during 'make'. These will be copied
  1376. to INSTALLBIN during 'make install'
  1377.  
  1378. =item INST_EXE
  1379.  
  1380. Old name for INST_SCRIPT. Deprecated. Please use INST_SCRIPT if you
  1381. need to use it.
  1382.  
  1383. =item INST_LIB
  1384.  
  1385. Directory where we put library files of this extension while building
  1386. it.
  1387.  
  1388. =item INST_MAN1DIR
  1389.  
  1390. Directory to hold the man pages at 'make' time
  1391.  
  1392. =item INST_MAN3DIR
  1393.  
  1394. Directory to hold the man pages at 'make' time
  1395.  
  1396. =item INST_SCRIPT
  1397.  
  1398. Directory, where executable files should be installed during
  1399. 'make'. Defaults to "./blib/bin", just to have a dummy location during
  1400. testing. make install will copy the files in INST_SCRIPT to
  1401. INSTALLSCRIPT.
  1402.  
  1403. =item LDFROM
  1404.  
  1405. defaults to "$(OBJECT)" and is used in the ld command to specify
  1406. what files to link/load from (also see dynamic_lib below for how to
  1407. specify ld flags)
  1408.  
  1409. =item LIBPERL_A
  1410.  
  1411. The filename of the perllibrary that will be used together with this
  1412. extension. Defaults to libperl.a.
  1413.  
  1414. =item LIB
  1415.  
  1416. LIB can only be set at C<perl Makefile.PL> time. It has the effect of
  1417. setting both INSTALLPRIVLIB and INSTALLSITELIB to that value regardless any
  1418.  
  1419. =item LIBS
  1420.  
  1421. An anonymous array of alternative library
  1422. specifications to be searched for (in order) until
  1423. at least one library is found. E.g.
  1424.  
  1425.   'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
  1426.  
  1427. Mind, that any element of the array
  1428. contains a complete set of arguments for the ld
  1429. command. So do not specify
  1430.  
  1431.   'LIBS' => ["-ltcl", "-ltk", "-lX11"]
  1432.  
  1433. See ODBM_File/Makefile.PL for an example, where an array is needed. If
  1434. you specify a scalar as in
  1435.  
  1436.   'LIBS' => "-ltcl -ltk -lX11"
  1437.  
  1438. MakeMaker will turn it into an array with one element.
  1439.  
  1440. =item LINKTYPE
  1441.  
  1442. 'static' or 'dynamic' (default unless usedl=undef in
  1443. config.sh). Should only be used to force static linking (also see
  1444. linkext below).
  1445.  
  1446. =item MAKEAPERL
  1447.  
  1448. Boolean which tells MakeMaker, that it should include the rules to
  1449. make a perl. This is handled automatically as a switch by
  1450. MakeMaker. The user normally does not need it.
  1451.  
  1452. =item MAKEFILE
  1453.  
  1454. The name of the Makefile to be produced.
  1455.  
  1456. =item MAN1PODS
  1457.  
  1458. Hashref of pod-containing files. MakeMaker will default this to all
  1459. EXE_FILES files that include POD directives. The files listed
  1460. here will be converted to man pages and installed as was requested
  1461. at Configure time.
  1462.  
  1463. =item MAN3PODS
  1464.  
  1465. Hashref of .pm and .pod files. MakeMaker will default this to all
  1466.  .pod and any .pm files that include POD directives. The files listed
  1467. here will be converted to man pages and installed as was requested
  1468. at Configure time.
  1469.  
  1470. =item MAP_TARGET
  1471.  
  1472. If it is intended, that a new perl binary be produced, this variable
  1473. may hold a name for that binary. Defaults to perl
  1474.  
  1475. =item MYEXTLIB
  1476.  
  1477. If the extension links to a library that it builds set this to the
  1478. name of the library (see SDBM_File)
  1479.  
  1480. =item NAME
  1481.  
  1482. Perl module name for this extension (DBD::Oracle). This will default
  1483. to the directory name but should be explicitly defined in the
  1484. Makefile.PL.
  1485.  
  1486. =item NEEDS_LINKING
  1487.  
  1488. MakeMaker will figure out, if an extension contains linkable code
  1489. anywhere down the directory tree, and will set this variable
  1490. accordingly, but you can speed it up a very little bit, if you define
  1491. this boolean variable yourself.
  1492.  
  1493. =item NOECHO
  1494.  
  1495. Defaults to C<@>. By setting it to an empty string you can generate a
  1496. Makefile that echos all commands. Mainly used in debugging MakeMaker
  1497. itself.
  1498.  
  1499. =item NORECURS
  1500.  
  1501. Boolean.  Attribute to inhibit descending into subdirectories.
  1502.  
  1503. =item OBJECT
  1504.  
  1505. List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
  1506. string containing all object files, e.g. "tkpBind.o
  1507. tkpButton.o tkpCanvas.o"
  1508.  
  1509. =item OPTIMIZE
  1510.  
  1511. Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
  1512. passed to subdirectory makes.
  1513.  
  1514. =item PERL
  1515.  
  1516. Perl binary for tasks that can be done by miniperl
  1517.  
  1518. =item PERLMAINCC
  1519.  
  1520. The call to the program that is able to compile perlmain.c. Defaults
  1521. to $(CC).
  1522.  
  1523. =item PERL_ARCHLIB
  1524.  
  1525. Same as above for architecture dependent files
  1526.  
  1527. =item PERL_LIB
  1528.  
  1529. Directory containing the Perl library to use.
  1530.  
  1531. =item PERL_SRC
  1532.  
  1533. Directory containing the Perl source code (use of this should be
  1534. avoided, it may be undefined)
  1535.  
  1536. =item PERM_RW
  1537.  
  1538. Desired Permission for read/writable files. Defaults to C<644>.
  1539. See also L<MM_Unix/perm_rw>.
  1540.  
  1541. =item PERM_RWX
  1542.  
  1543. Desired permission for executable files. Defaults to C<755>.
  1544. See also L<MM_Unix/perm_rwx>.
  1545.  
  1546. =item PL_FILES
  1547.  
  1548. Ref to hash of files to be processed as perl programs. MakeMaker
  1549. will default to any found *.PL file (except Makefile.PL) being keys
  1550. and the basename of the file being the value. E.g.
  1551.  
  1552.   {'foobar.PL' => 'foobar'}
  1553.  
  1554. The *.PL files are expected to produce output to the target files
  1555. themselves.
  1556.  
  1557. =item PM
  1558.  
  1559. Hashref of .pm files and *.pl files to be installed.  e.g.
  1560.  
  1561.   {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
  1562.  
  1563. By default this will include *.pm and *.pl and the files found in
  1564. the PMLIBDIRS directories.  Defining PM in the
  1565. Makefile.PL will override PMLIBDIRS.
  1566.  
  1567. =item PMLIBDIRS
  1568.  
  1569. Ref to array of subdirectories containing library files.  Defaults to
  1570. [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
  1571. they contain will be installed in the corresponding location in the
  1572. library.  A libscan() method can be used to alter the behaviour.
  1573. Defining PM in the Makefile.PL will override PMLIBDIRS.
  1574.  
  1575. =item PREFIX
  1576.  
  1577. Can be used to set the three INSTALL* attributes in one go (except for
  1578. probably INSTALLMAN1DIR, if it is not below PREFIX according to
  1579. %Config).  They will have PREFIX as a common directory node and will
  1580. branch from that node into lib/, lib/ARCHNAME or whatever Configure
  1581. decided at the build time of your perl (unless you override one of
  1582. them, of course).
  1583.  
  1584. =item PREREQ_PM
  1585.  
  1586. Hashref: Names of modules that need to be available to run this
  1587. extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
  1588. desired version is the value. If the required version number is 0, we
  1589. only check if any version is installed already.
  1590.  
  1591. =item SKIP
  1592.  
  1593. Arryref. E.g. [qw(name1 name2)] skip (do not write) sections of the
  1594. Makefile. Caution! Do not use the SKIP attribute for the neglectible
  1595. speedup. It may seriously damage the resulting Makefile. Only use it,
  1596. if you really need it.
  1597.  
  1598. =item TYPEMAPS
  1599.  
  1600. Ref to array of typemap file names.  Use this when the typemaps are
  1601. in some directory other than the current directory or when they are
  1602. not named B<typemap>.  The last typemap in the list takes
  1603. precedence.  A typemap in the current directory has highest
  1604. precedence, even if it isn't listed in TYPEMAPS.  The default system
  1605. typemap has lowest precedence.
  1606.  
  1607. =item VERSION
  1608.  
  1609. Your version number for distributing the package.  This defaults to
  1610. 0.1.
  1611.  
  1612. =item VERSION_FROM
  1613.  
  1614. Instead of specifying the VERSION in the Makefile.PL you can let
  1615. MakeMaker parse a file to determine the version number. The parsing
  1616. routine requires that the file named by VERSION_FROM contains one
  1617. single line to compute the version number. The first line in the file
  1618. that contains the regular expression
  1619.  
  1620.     /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
  1621.  
  1622. will be evaluated with eval() and the value of the named variable
  1623. B<after> the eval() will be assigned to the VERSION attribute of the
  1624. MakeMaker object. The following lines will be parsed o.k.:
  1625.  
  1626.     $VERSION = '1.00';
  1627.     *VERSION = \'1.01';
  1628.     ( $VERSION ) = '$Revision: 1.222 $ ' =~ /\$Revision:\s+([^\s]+)/;
  1629.     $FOO::VERSION = '1.10';
  1630.     *FOO::VERSION = \'1.11';
  1631.  
  1632. but these will fail:
  1633.  
  1634.     my $VERSION = '1.01';
  1635.     local $VERSION = '1.02';
  1636.     local $FOO::VERSION = '1.30';
  1637.  
  1638. The file named in VERSION_FROM is not added as a dependency to
  1639. Makefile. This is not really correct, but it would be a major pain
  1640. during development to have to rewrite the Makefile for any smallish
  1641. change in that file. If you want to make sure that the Makefile
  1642. contains the correct VERSION macro after any change of the file, you
  1643. would have to do something like
  1644.  
  1645.     depend => { Makefile => '$(VERSION_FROM)' }
  1646.  
  1647. See attribute C<depend> below.
  1648.  
  1649. =item XS
  1650.  
  1651. Hashref of .xs files. MakeMaker will default this.  e.g.
  1652.  
  1653.   {'name_of_file.xs' => 'name_of_file.c'}
  1654.  
  1655. The .c files will automatically be included in the list of files
  1656. deleted by a make clean.
  1657.  
  1658. =item XSOPT
  1659.  
  1660. String of options to pass to xsubpp.  This might include C<-C++> or
  1661. C<-extern>.  Do not include typemaps here; the TYPEMAP parameter exists for
  1662. that purpose.
  1663.  
  1664. =item XSPROTOARG
  1665.  
  1666. May be set to an empty string, which is identical to C<-prototypes>, or
  1667. C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
  1668. defaults to the empty string.
  1669.  
  1670. =item XS_VERSION
  1671.  
  1672. Your version number for the .xs file of this package.  This defaults
  1673. to the value of the VERSION attribute.
  1674.  
  1675. =back
  1676.  
  1677. =head2 Additional lowercase attributes
  1678.  
  1679. can be used to pass parameters to the methods which implement that
  1680. part of the Makefile.
  1681.  
  1682. =over 2
  1683.  
  1684. =item clean
  1685.  
  1686.   {FILES => "*.xyz foo"}
  1687.  
  1688. =item depend
  1689.  
  1690.   {ANY_TARGET => ANY_DEPENDECY, ...}
  1691.  
  1692. =item dist
  1693.  
  1694.   {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
  1695.   SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
  1696.   ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
  1697.  
  1698. If you specify COMPRESS, then SUFFIX should also be altered, as it is
  1699. needed to tell make the target file of the compression. Setting
  1700. DIST_CP to ln can be useful, if you need to preserve the timestamps on
  1701. your files. DIST_CP can take the values 'cp', which copies the file,
  1702. 'ln', which links the file, and 'best' which copies symbolic links and
  1703. links the rest. Default is 'best'.
  1704.  
  1705. =item dynamic_lib
  1706.  
  1707.   {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
  1708.  
  1709. =item installpm
  1710.  
  1711. Deprecated as of MakeMaker 5.23. See L<ExtUtils::MM_Unix/pm_to_blib>.
  1712.  
  1713. =item linkext
  1714.  
  1715.   {LINKTYPE => 'static', 'dynamic' or ''}
  1716.  
  1717. NB: Extensions that have nothing but *.pm files had to say
  1718.  
  1719.   {LINKTYPE => ''}
  1720.  
  1721. with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
  1722. can be deleted safely. MakeMaker recognizes, when there's nothing to
  1723. be linked.
  1724.  
  1725. =item macro
  1726.  
  1727.   {ANY_MACRO => ANY_VALUE, ...}
  1728.  
  1729. =item realclean
  1730.  
  1731.   {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
  1732.  
  1733. =item tool_autosplit
  1734.  
  1735.   {MAXLEN =E<gt> 8}
  1736.  
  1737. =back
  1738.  
  1739. =cut
  1740.  
  1741. # bug in pod2html, so leave the =back
  1742.  
  1743. # Don't delete this cut, MM depends on it!
  1744.  
  1745. =head2 Overriding MakeMaker Methods
  1746.  
  1747. If you cannot achieve the desired Makefile behaviour by specifying
  1748. attributes you may define private subroutines in the Makefile.PL.
  1749. Each subroutines returns the text it wishes to have written to
  1750. the Makefile. To override a section of the Makefile you can
  1751. either say:
  1752.  
  1753.     sub MY::c_o { "new literal text" }
  1754.  
  1755. or you can edit the default by saying something like:
  1756.  
  1757.     sub MY::c_o {
  1758.         package MY;    # so that "SUPER" works right
  1759.         my $inherited = shift->SUPER::c_o(@_);
  1760.         $inherited =~ s/old text/new text/;
  1761.         $inherited;
  1762.     }
  1763.  
  1764. If you are running experiments with embedding perl as a library into
  1765. other applications, you might find MakeMaker is not sufficient. You'd
  1766. better have a look at ExtUtils::Embed which is a collection of utilities
  1767. for embedding.
  1768.  
  1769. If you still need a different solution, try to develop another
  1770. subroutine that fits your needs and submit the diffs to
  1771. F<perl5-porters@perl.org> or F<comp.lang.perl.moderated> as appropriate.
  1772.  
  1773. For a complete description of all MakeMaker methods see L<ExtUtils::MM_Unix>.
  1774.  
  1775. Here is a simple example of how to add a new target to the generated
  1776. Makefile:
  1777.  
  1778.     sub MY::postamble {
  1779.     '
  1780.     $(MYEXTLIB): sdbm/Makefile
  1781.         cd sdbm && $(MAKE) all
  1782.     ';
  1783.     }
  1784.  
  1785.  
  1786. =head2 Hintsfile support
  1787.  
  1788. MakeMaker.pm uses the architecture specific information from
  1789. Config.pm. In addition it evaluates architecture specific hints files
  1790. in a C<hints/> directory. The hints files are expected to be named
  1791. like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
  1792. name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
  1793. MakeMaker within the WriteMakefile() subroutine, and can be used to
  1794. execute commands as well as to include special variables. The rules
  1795. which hintsfile is chosen are the same as in Configure.
  1796.  
  1797. The hintsfile is eval()ed immediately after the arguments given to
  1798. WriteMakefile are stuffed into a hash reference $self but before this
  1799. reference becomes blessed. So if you want to do the equivalent to
  1800. override or create an attribute you would say something like
  1801.  
  1802.     $self->{LIBS} = ['-ldbm -lucb -lc'];
  1803.  
  1804. =head2 Distribution Support
  1805.  
  1806. For authors of extensions MakeMaker provides several Makefile
  1807. targets. Most of the support comes from the ExtUtils::Manifest module,
  1808. where additional documentation can be found.
  1809.  
  1810. =over 4
  1811.  
  1812. =item    make distcheck
  1813.  
  1814. reports which files are below the build directory but not in the
  1815. MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
  1816. details)
  1817.  
  1818. =item    make skipcheck
  1819.  
  1820. reports which files are skipped due to the entries in the
  1821. C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
  1822. details)
  1823.  
  1824. =item    make distclean
  1825.  
  1826. does a realclean first and then the distcheck. Note that this is not
  1827. needed to build a new distribution as long as you are sure, that the
  1828. MANIFEST file is ok.
  1829.  
  1830. =item    make manifest
  1831.  
  1832. rewrites the MANIFEST file, adding all remaining files found (See
  1833. ExtUtils::Manifest::mkmanifest() for details)
  1834.  
  1835. =item    make distdir
  1836.  
  1837. Copies all the files that are in the MANIFEST file to a newly created
  1838. directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
  1839. exists, it will be removed first.
  1840.  
  1841. =item    make disttest
  1842.  
  1843. Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
  1844. a make test in that directory.
  1845.  
  1846. =item    make tardist
  1847.  
  1848. First does a distdir. Then a command $(PREOP) which defaults to a null
  1849. command, followed by $(TOUNIX), which defaults to a null command under
  1850. UNIX, and will convert files in distribution directory to UNIX format
  1851. otherwise. Next it runs C<tar> on that directory into a tarfile and
  1852. deletes the directory. Finishes with a command $(POSTOP) which
  1853. defaults to a null command.
  1854.  
  1855. =item    make dist
  1856.  
  1857. Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
  1858.  
  1859. =item    make uutardist
  1860.  
  1861. Runs a tardist first and uuencodes the tarfile.
  1862.  
  1863. =item    make shdist
  1864.  
  1865. First does a distdir. Then a command $(PREOP) which defaults to a null
  1866. command. Next it runs C<shar> on that directory into a sharfile and
  1867. deletes the intermediate directory again. Finishes with a command
  1868. $(POSTOP) which defaults to a null command.  Note: For shdist to work
  1869. properly a C<shar> program that can handle directories is mandatory.
  1870.  
  1871. =item    make zipdist
  1872.  
  1873. First does a distdir. Then a command $(PREOP) which defaults to a null
  1874. command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
  1875. zipfile. Then deletes that directory. Finishes with a command
  1876. $(POSTOP) which defaults to a null command.
  1877.  
  1878. =item    make ci
  1879.  
  1880. Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
  1881.  
  1882. =back
  1883.  
  1884. Customization of the dist targets can be done by specifying a hash
  1885. reference to the dist attribute of the WriteMakefile call. The
  1886. following parameters are recognized:
  1887.  
  1888.     CI           ('ci -u')
  1889.     COMPRESS     ('gzip --best')
  1890.     POSTOP       ('@ :')
  1891.     PREOP        ('@ :')
  1892.     TO_UNIX      (depends on the system)
  1893.     RCS_LABEL    ('rcs -q -Nv$(VERSION_SYM):')
  1894.     SHAR         ('shar')
  1895.     SUFFIX       ('.gz')
  1896.     TAR          ('tar')
  1897.     TARFLAGS     ('cvf')
  1898.     ZIP          ('zip')
  1899.     ZIPFLAGS     ('-r')
  1900.  
  1901. An example:
  1902.  
  1903.     WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
  1904.  
  1905. =head2 Disabling an extension
  1906.  
  1907. If some events detected in F<Makefile.PL> imply that there is no way
  1908. to create the Module, but this is a normal state of things, then you
  1909. can create a F<Makefile> which does nothing, but succeeds on all the
  1910. "usual" build targets.  To do so, use
  1911.  
  1912.    ExtUtils::MakeMaker::WriteEmptyMakefile();
  1913.  
  1914. instead of WriteMakefile().
  1915.  
  1916. This may be useful if other modules expect this module to be I<built>
  1917. OK, as opposed to I<work> OK (say, this system-dependent module builds
  1918. in a subdirectory of some other distribution, or is listed as a
  1919. dependency in a CPAN::Bundle, but the functionality is supported by
  1920. different means on the current architecture).
  1921.  
  1922. =head1 SEE ALSO
  1923.  
  1924. ExtUtils::MM_Unix, ExtUtils::Manifest, ExtUtils::testlib,
  1925. ExtUtils::Install, ExtUtils::Embed
  1926.  
  1927. =head1 AUTHORS
  1928.  
  1929. Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, Andreas KE<ouml>nig
  1930. <F<A.Koenig@franz.ww.TU-Berlin.DE>>, Tim Bunce <F<Tim.Bunce@ig.co.uk>>.
  1931. VMS support by Charles Bailey <F<bailey@genetics.upenn.edu>>.  OS/2
  1932. support by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>.  Contact the
  1933. makemaker mailing list C<mailto:makemaker@franz.ww.tu-berlin.de>, if
  1934. you have any questions.
  1935.  
  1936. =cut
  1937.